﻿using Microsoft.Extensions.Caching.Memory;
using Sage.Caching.Memory.Models;

namespace Sage.Caching.Memory.Services
{
    /// <summary>
    /// 定义内存缓存服务的接口。
    /// </summary>
    public interface ICacheService : IDisposable
    {
        /// <summary>
        /// 尝试通过指定的键从缓存中获取值。
        /// </summary>
        /// <typeparam name="T">缓存项的类型。</typeparam>
        /// <param name="key">缓存项的键。</param>
        /// <param name="value">如果找到缓存项，则返回该项的值；否则为默认值。</param>
        /// <returns>操作是否成功。</returns>
        bool TryGetValue<T>(string key, out T? value);

        /// <summary>
        /// 设置指定的缓存项。
        /// </summary>
        /// <typeparam name="T">缓存项的类型。</typeparam>
        /// <param name="key">缓存项的键。</param>
        /// <param name="value">要缓存的值。</param>
        /// <param name="region">区域名称（用于逻辑分组）。</param>
        /// <param name="options">缓存项的配置选项。如果未指定则使用默认配置。</param>
        void Set<T>(string key, T value, string? region = null, MemoryCacheEntryOptions? options = null);

        /// <summary>
        /// 移除指定键的缓存项。
        /// </summary>
        /// <param name="key">要移除的键。</param>
        /// <param name="region">区域名称（逻辑分组中的信息）</param>
        void Remove(string key, string? region = null);

        /// <summary>
        /// 获取一项缓存，如果不存在则进行创建。
        /// </summary>
        /// <typeparam name="T">缓存项的类型。</typeparam>
        /// <param name="key">缓存项的键。</param>
        /// <param name="valueFactory">创建缓存值的工厂方法。</param>
        /// <param name="region">区域名称（用于逻辑分组）。</param>
        /// <param name="options">缓存项的配置选项。如果未指定则使用默认配置。</param>
        /// <returns>缓存中的值或新创建的值。</returns>
        T? GetOrCreate<T>(string key, Func<T> valueFactory, string? region = null, MemoryCacheEntryOptions? options = null);

        /// <summary>
        /// 异步获取一项缓存，如果不存在则异步创建。
        /// </summary>
        /// <typeparam name="T">缓存项的类型。</typeparam>
        /// <param name="key">缓存项的键。</param>
        /// <param name="valueFactory">异步创建缓存值的工厂方法。</param>
        /// <param name="region">区域名称（用于逻辑分组）。</param>
        /// <param name="options">缓存项的配置选项。如果未指定则使用默认配置。</param>
        /// <returns>包含缓存值的任务。</returns>
        ValueTask<T?> GetOrCreateAsync<T>(string key, Func<ValueTask<T>> valueFactory, string? region = null, MemoryCacheEntryOptions? options = null);

        /// <summary>
        /// 移除所有缓存项。
        /// </summary>
        void Clear();

        /// <summary>
        /// 清除指定的区域中所有缓存项。
        /// </summary>
        /// <param name="region">区域名称。</param>
        /// <returns>被移除的项数量。</returns>
        int ClearRegion(string region);

        /// <summary>
        /// 批量设置多个缓存项。
        /// </summary>
        /// <typeparam name="T">缓存项的类型。</typeparam>
        /// <param name="items">要设置的键值对。</param>
        /// <param name="region">区域名称（用于逻辑分组）。</param>
        /// <param name="options">缓存项的配置选项。如果未指定则使用默认配置。</param>
        void SetMany<T>(IEnumerable<KeyValuePair<string, T>> items, string? region = null, MemoryCacheEntryOptions? options = null);

        /// <summary>
        /// 批量移除多个缓存项。
        /// </summary>
        /// <param name="keys">要移除的键集合。</param>
        /// <returns>实际移除的项数量。</returns>
        int RemoveMany(IEnumerable<string> keys);

        /// <summary>
        /// 获取缓存的统计信息。
        /// </summary>
        /// <returns>缓存统计信息。</returns>
        CacheStats GetCacheStats();

        /// <summary>
        /// 获取指定区域中的所有键。
        /// </summary>
        /// <param name="region">区域名称。</param>
        /// <returns>区域中的键集合。</returns>
        IReadOnlyCollection<string> GetRegionKeys(string region);
    }
}
